---
title: NPM에 게시
description: Astro 컴포넌트를 NPM에 게시하는 방법 알아보기
i18nReady: true
---

import { FileTree } from '@astrojs/starlight/components';

새로운 Astro 컴포넌트를 구축하시나요? **[npm](https://npmjs.com/)에 게시하세요!**

Astro 컴포넌트를 게시하는 것은 프로젝트 전반에 걸쳐 기존 작업을 재사용하고 더 넓은 Astro 커뮤니티와 공유할 수 있는 좋은 방법입니다. Astro 컴포넌트는 다른 JavaScript 패키지와 마찬가지로 NPM에 직접 게시하고 설치할 수 있습니다.

영감을 찾고 계신가요? Astro 커뮤니티에서 우리가 가장 좋아하는 [테마](https://astro.build/themes/)와 [컴포넌트](https://astro.build/integrations/)를 확인해 보세요. 전체 공개 카탈로그를 보기 위해 [npm을 검색](https://www.npmjs.com/search?q=keywords:astro-component,withastro)할 수도 있습니다.

:::tip[혼자 시작하고 싶지 않으신가요?]
커뮤니티에서 지원하는 기본 템플릿을 보려면 [Astro 커뮤니티의 컴포넌트 템플릿](https://github.com/astro-community/component-template)을 확인하세요!
:::

## 빠른 시작

컴포넌트 개발을 빠르게 시작하기 위해 이미 설정된 템플릿을 사용할 수 있습니다.

```bash
# 새 디렉터리에서 Astro 컴포넌트 템플릿을 초기화합니다.
npm create astro@latest my-new-component-directory -- --template component
# yarn
yarn create astro my-new-component-directory --template component
# pnpm
pnpm create astro@latest my-new-component-directory -- --template component
```

## 패키지 생성

:::note[전제조건]
시작하기 전에 다음 사항에 대한 기본적인 이해를 갖추는 것이 도움이 됩니다.

- [Node 모듈](https://docs.npmjs.com/creating-node-js-modules)
- [패키지 매니페스트 (`package.json`)](https://docs.npmjs.com/creating-a-package-json-file)
- [워크스페이스](https://docs.npmjs.com/cli/v7/configuring-npm/package-json#workspaces)
:::

새 패키지를 만들려면 프로젝트에서 **워크스페이스**을 사용하도록 개발 환경을 구성하세요. 이를 통해 Astro의 작업 복사본과 함께 컴포넌트를 개발할 수 있습니다.

<FileTree>
- my-new-component-directory/
  - demo/
    - ... 테스트 및 시연용
  - package.json
  - packages/
    - my-component/
      - index.js
      - package.json
      - ... 패키지에서 사용되는 추가 파일
</FileTree>

`my-project`라는 이 예시는 `my-component`라는 단일 패키지와 컴포넌트를 테스트하고 시연하기 위한 `demo/` 디렉터리가 포함된 프로젝트를 만듭니다.

이는 프로젝트 루트의 `package.json` 파일에서 구성됩니다.

```json
{
  "name": "my-project",
  "workspaces": ["demo", "packages/*"]
}
```

이 예시에서는 `packages` 디렉터리에서 여러 패키지를 함께 개발할 수 있습니다. 이 패키지는 Astro의 작업 복사본을 설치할 수 있는 `demo`에서 참조할 수도 있습니다.

```shell
npm create astro@latest demo -- --template minimal
# yarn
yarn create astro demo --template minimal
# pnpm
pnpm create astro@latest demo -- --template minimal
```

개별 패키지를 구성하는 두 개의 초기 파일은 `package.json`과 `index.js`입니다.

### `package.json`

패키지 디렉터리의 `package.json` 파일에는 설명, 종속성, 기타 패키지 메타데이터를 포함하여 패키지와 관련된 모든 정보가 포함되어 있습니다.

```json
{
  "name": "my-component",
  "description": "Component description",
  "version": "1.0.0",
  "homepage": "https://github.com/owner/project#readme",
  "type": "module",
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  },
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"],
  "keywords": ["astro", "withastro", "astro-component", "...", "..."]
}
```

#### `description`

다른 사람들이 해당 컴포넌트의 기능을 알 수 있도록 돕기 위해 사용되는 컴포넌트에 대한 간단한 설명입니다.

```json
{
  "description": "An Astro Element Generator"
}
```

#### `type`

Node.js와 Astro가 `index.js` 파일을 해석하기 위해 사용하는 모듈의 타입입니다.

```json
{
  "type": "module"
}
```

`index.js` 파일을 `import` 및 `export`의 엔트리포인트로 사용할 수 있도록 `"type": "module"`을 사용하세요.

#### `homepage`

프로젝트 홈페이지의 URL입니다.

```json
{
  "homepage": "https://github.com/owner/project#readme"
}
```

이는 사용자를 프로젝트의 온라인 데모, 문서, 홈페이지로 안내하는 좋은 방법입니다.

#### `exports`

이름으로 가져올 때 패키지의 엔트리포인트입니다.

```json
{
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  }
}
```

이 예시에서 `my-component` 가져오기는 `index.js`를 사용하고 `my-component/astro` 또는 `my-component/react` 가져오기는 각각 `MyAstroComponent.astro` 또는 `MyReactComponent.jsx`를 사용합니다.

#### `files`

npm을 통해 사용자에게 제공되는 번들에서 불필요한 파일을 제외하는 선택적 최적화입니다. **여기에 나열된 파일만 패키지에 포함됩니다**. 따라서 패키지가 작동하는 데 필요한 파일을 추가하거나 변경하는 경우 이 목록을 업데이트해야 합니다.

```json
{
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"]
}
```

#### `keywords`

다른 사람들이 [npm](https://www.npmjs.com/search?q=keywords:astro-component,withastro) 및 기타 검색 카탈로그에서 여러분의 컴포넌트를 찾는 데 도움이 되는 컴포넌트와 관련된 키워드 배열입니다.

Astro 생태계에서 검색 가능성을 극대화하려면 `astro-component` 또는 `withastro`를 특수 키워드로 추가하세요.

```json
{
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}
```

:::tip
키워드는 [통합 라이브러리](https://astro.build/integrations/)에서도 사용됩니다! NPM에서 찾는 키워드의 전체 목록은 [아래를 참조하세요](#통합-라이브러리).
:::

---

### `index.js`

패키지를 가져올 때마다 사용되는 기본 **패키지 엔트리포인트**입니다.

```js
export { default as MyAstroComponent } from './MyAstroComponent.astro';

export { default as MyReactComponent } from './MyReactComponent.jsx';
```

이를 통해 여러 컴포넌트를 단일 인터페이스로 함께 패키징할 수 있습니다.

#### 예: 명명된 가져오기 사용

```astro
---
import { MyAstroComponent } from 'my-component';
import { MyReactComponent } from 'my-component';
---
<MyAstroComponent />
<MyReactComponent />
```

#### 예: 네임스페이스 가져오기 사용

```astro
---
import * as Example from 'example-astro-component';
---
<Example.MyAstroComponent />
<Example.MyReactComponent />
```

#### 예: 개별 가져오기 사용

```astro
---
import MyAstroComponent from 'example-astro-component/astro';
import MyReactComponent from 'example-astro-component/react';
---
<MyAstroComponent />
<MyReactComponent />
```

---

## 패키지 개발

Astro에는 개발을 위한 전용 '패키지 모드'가 없습니다. 대신 데모 프로젝트를 사용하여 프로젝트에서 패키지를 개발하고 테스트해야 합니다. 이는 개발에만 사용되는 개인 웹사이트일 수도 있고 패키지에 대한 공개 데모/문서 웹사이트일 수도 있습니다.

기존 프로젝트에서 컴포넌트를 추출하는 경우 해당 프로젝트를 계속 사용하여 현재 추출된 컴포넌트를 개발할 수도 있습니다.

## 컴포넌트 테스트

Astro는 현재 테스트 러너를 출시하지 않았습니다. _(이 문제에 관심이 있으시면 [Discord에 참여하세요!](https://astro.build/chat))_

그동안 테스트에 대한 현재 권장 사항은 다음과 같습니다.

1. `demo/src/pages` 디렉터리에 테스트 `fixtures` 디렉터리를 추가하세요.
2. 실행하려는 모든 테스트에 대해 새 페이지를 추가하세요.
3. 각 페이지에는 테스트하려는 다양한 컴포넌트 사용법이 포함되어야 합니다.
4. `astro build` 명령을 실행하여 fixtures를 빌드한 다음, `dist/__fixtures__/` 디렉터리에 있는 결과물을 예상한 것과 비교하세요.

<FileTree>
- my-project/demo/src/pages/\_\_fixtures\_\_/
  - test-name-01.astro
  - test-name-02.astro
  - test-name-03.astro
</FileTree>

## 컴포넌트 게시

패키지가 준비되면 `npm publish` 명령을 사용하여 npm에 게시할 수 있습니다. 실패하면 `npm login`을 통해 로그인했는지, `package.json` 파일이 올바른지 확인하세요. 성공하면 끝입니다!

Astro 패키지에는 `build` 단계가 없다는 점에 유의하세요. `.astro`, `.ts`, `.jsx`, `.css` 등 Astro가 기본적으로 지원하는 모든 파일 형식은 빌드 단계 없이 직접 게시할 수 있습니다.

Astro에서 기본적으로 지원하지 않는 다른 파일 형식이 필요한 경우 패키지에 빌드 단계를 추가하세요. 이 고급 연습은 여러분에게 달려 있습니다.

## 통합 라이브러리

[통합 라이브러리](https://astro.build/integrations/)에 통합을 추가하여 여러분의 노력을 공유하세요!

:::tip
통합을 구축하는 데 도움이 필요하거나 다른 통합 빌더가 필요하신가요? [Discord 서버](https://astro.build/chat)에는 전용 `#integrations` 채널이 있습니다. 방문하여 인사를 나누세요!
:::

### `package.json` 데이터

라이브러리는 매주 자동으로 업데이트되어 `astro-component` 또는 `withastro` 키워드를 사용하여 NPM에 게시된 모든 패키지를 가져옵니다.

통합 라이브러리는 `package.json` 파일에서 `name`, `description`, `repository`, `homepage` 데이터를 읽습니다.

아바타는 라이브러리에서 브랜드를 강조할 수 있는 좋은 방법입니다! 패키지가 게시되면 아바타를 첨부하여 [GitHub issue를 제출](https://github.com/withastro/astro.build/issues/new/choose)할 수 있으며 목록에 추가해 드리겠습니다.

:::tip
우리의 라이브러리가 NPM에서 읽는 정보를 재정의해야 합니까? 괜찮아요! 업데이트된 정보로 [issue를 제출](https://github.com/withastro/astro.build/issues/new/choose)해 주시면 맞춤 `name`, `description`, `homepage`가 대신 사용되도록 하겠습니다.
:::

### 컬렉션

필수 키워드인 `astro-component` 또는 `withastro` 키워드 외에도 패키지를 자동으로 구성하는 데 특수 키워드도 사용됩니다. 아래 키워드 중 하나를 포함하면 통합 라이브러리의 컬렉션에 통합이 추가됩니다.

| 컬렉션        | 키워드                                     |
|------------------ | -------------------------------------------- |
| 접근성     | `a11y`, `accessibility`                      |
| 어댑터          | `astro-adapter`                              |
| 분석         | `analytics`                                  |
| CSS + UI          | `css`, `ui`, `icon`, `icons`, `renderer`     |
| 프레임워크        | `renderer`                                   |
| 성능 + SEO | `performance`, `perf`, `seo`, `optimization` |

## 공유

우리는 여러분의 작업을 공유하도록 권장하며, 우리의 재능 있는 Astronauts가 창조하는 것을 보는 것을 정말 좋아합니다. 오셔서 여러분이 만든 것을 [Discord](https://astro.build/chat)에서 공유하거나 트윗에서 [@astrodotbuild](https://twitter.com/astrodotbuild)를 멘션해 주세요!
